feat(resolver): deterministic IPv6 ext-IP discovery via per-family probes (#220) - #225

…x, tests, CI) (#230)

* chore: migrate from Poetry to uv (closes #105)

Issue #105 has been open since 2022, originally about consolidating onto
Poetry-only. With uv 0.11.13 mature and 10-30× faster than Poetry, the
calculus shifted. Migrate the entire dev/CI/Docker toolchain to uv in one
pass.

Why uv now:
- 10-30× faster resolve (matters most across the Py 3.10-3.14 CI matrix)
- PEP 621 [project] + PEP 735 [dependency-groups] native (standards-track,
  not Poetry-specific)
- Single binary replaces Poetry's role for install/lock/sync/run
- Build backend stays poetry-core>=2.1.3; poetry-core 2.x reads PEP 621
  natively, so PyPI publish (`python -m build`) keeps working unchanged

Migration scope (one-pass per the matrix-audit-fix-in-one-pass methodology
from PR #225 / PR #210):

pyproject.toml
- [tool.poetry.*] sections → PEP 621 [project] + [dependency-groups.dev]
- caret constraints (^X.Y.Z) → PEP 440 explicit ranges (>=X.Y.Z,<(X+1).0.0)
- ruff added to dev group (was previously installed ad-hoc in CI)
- pytest-runner dropped (deprecated, no longer needed)

Lockfile transition
- Generated fresh uv.lock (33 packages resolved in 642ms)
- Verified resolution parity vs poetry.lock: no major-version drift on
  any direct dep; only minor/patch bumps within constraints
- Deleted poetry.lock; removed uv.lock from .gitignore

CI workflows
- python-test-versions.yml: snok/install-poetry → astral-sh/setup-uv@v8.1.0
  (SHA-pinned), poetry install → `uv sync --locked --dev`, all `poetry run`
  → `uv run`. Added `enable-cache: true`.
- py-to-exe.yml: same pattern. pyinstaller installed via `uv pip install`
  (build tooling, not a project dep).
- python-publish.yml: unchanged (already uses `python -m build`).

Dockerfile
- pip install poetry → COPY --from=ghcr.io/astral-sh/uv:0.11.13 (tag+digest
  pinned, same pattern as the python:3.14-slim base).
- Multi-stage layout: deps layer (`uv sync --no-install-project --no-dev`)
  separated from project layer for better cache hit rate.
- ENTRYPOINT keeps `python -m proxybroker` via PATH=/app/.venv/bin.

Docs
- README "Development Setup": Poetry → uv (with `curl install uv` snippet
  for new contributors); Development Tools list updated.
- CLAUDE.md "Setup" + "Known Quirks" sections: Poetry → uv; clarified that
  poetry-core remains the build backend.

Verification (all green locally before push):
- uv lock: 33 packages, 642ms
- uv sync --locked --dev: succeeds
- uv run pytest -x: 293/293 passing
- uv run ruff check . + ruff format --check .: clean
- python -m build: sdist + wheel both build (validates poetry-core 2.x
  reading PEP 621 metadata)
- docker build + docker run --rm proxybroker2:uv-test --help: image
  builds in ~4s, CLI invokes correctly

Out of scope:
- docs/requirements.txt: used directly by ReadTheDocs, not part of dev
  workflow. Left as-is.
- MANIFEST.in: setuptools artifact, no change.
- .pre-commit-config.yaml: uses ruff/bandit standalone, no change.

Co-Authored-By: Claude <noreply@anthropic.com>

* chore: requirements.txt for Snyk (works around uv.lock unsupported)

Snyk's Python plugin doesn't yet support uv.lock files (snyk-python-plugin
#251 still open as of 2026-05-11), so the snyk PR check errors when
poetry.lock disappears in the migration. Generate requirements.txt from
uv.lock as a snyk-readable manifest until upstream support lands.

- requirements.txt: generated via `uv export --format requirements-txt
  --no-dev --no-emit-project`. Includes hashes; ~954 lines.
- .pre-commit-config.yaml: add a local hook that auto-regenerates the file
  whenever uv.lock or pyproject.toml changes. Uses `language: system` so
  it runs against whatever uv is on PATH.
- CLAUDE.md: document the workaround and the upstream issue, with a note
  to remove this once Snyk ships uv support.

Tradeoff: one auto-generated file in the repo with a clear "don't edit
by hand" mechanism. Better than carrying poetry.lock alongside uv.lock
(which would defeat the migration's purpose) or making snyk a non-blocking
check (security regression).

Co-Authored-By: Claude <noreply@anthropic.com>

* chore(snyk): generate requirements.txt without hashes

Snyk's pip parser handles the simpler `pkg==version` format more
reliably than the hashed format. Switch the export and the pre-commit
hook accordingly. Cuts the file from ~954 lines to ~53.

Co-Authored-By: Claude <noreply@anthropic.com>

* fix(ci): pair setup-python with setup-uv to get latest Python patch

CI failure on PR #230 commit 1558779: build (3.12) failed because the
runner used Python 3.12.3 (pre-installed on ubuntu-latest), not 3.12.11+.
Two tests assert RFC 5952 IPv4-mapped IPv6 string format
(`::ffff:192.0.2.1`), which Python only adopted in 3.12.4 (bpo-119891).

Root cause: setup-uv's `python-version: "3.12"` doesn't install the
LATEST 3.12 patch — it picks up whatever Python is already on PATH (the
runner's older pre-installed version).

Fix: install Python via `actions/setup-python` first (always picks the
latest patch for the requested minor), then run setup-uv WITHOUT the
`python-version` input. Pass `--python ${{ matrix.python-version }}` to
`uv sync` to pin uv to the version setup-python provided.

Same fix applied to py-to-exe.yml for consistency.

Co-Authored-By: Claude <noreply@anthropic.com>

* chore: --quiet on uv export so requirements.txt is clean

Earlier `uv export ... > requirements.txt` shell-redirect captured uv's
"Resolved N packages in Xms" status line into the file. Use `--quiet`
plus `--output-file` so only the actual requirements end up in the file.

Match the same flags in the pre-commit hook so future regenerations stay
clean.

Co-Authored-By: Claude <noreply@anthropic.com>

* fix(security): bump dep lower-bounds to clear known vulns at constraint floor

Snyk preview (now enabled) parses pyproject.toml's [project.dependencies]
correctly and flagged click@8.2.1 — the constraint `>=8.2.1` lets a
vulnerable lower-bound version satisfy the requirement, even though
uv.lock pins click==8.3.3.

Audit of all dep lower bounds against snyk's vulnerability database:

- click 8.2.1 → SNYK-PYTHON-CLICK-16347201, HIGH severity, command
  injection in click.edit() filename param. Fixed in 8.3.3.
- aiohttp 3.12.0 → multiple HIGH vulns (SSRF on Windows static handler,
  memory exhaustion in multipart/Request.post/ZLibDecompressor, request
  smuggling). Fixed in 3.13.4+.
- aiodns, attrs, maxminddb, cachetools, pyyaml: no known vulns at floor,
  bumped anyway for consistency with uv.lock.

Strategy: align all dep lower-bounds with what uv.lock currently
resolves. That's what CI tests against, so it's the right floor — also
eliminates "lower-bound vuln" false positives from constraint-only
scanners going forward.

- aiohttp: 3.12.0 → 3.13.5
- aiodns: 3.4.0 → 3.6.1
- attrs: 25.3.0 → 26.1.0
- maxminddb: 2.7.0 → 2.8.2
- cachetools: 5.5.2 (no change)
- click: 8.2.1 → 8.3.3
- pyyaml: 6.0.2 → 6.0.3
- pytest (dev): 8.3.5 → 8.4.2
- pytest-mock (dev): 3.14.0 → 3.15.1
- pytest-cov (dev): 6.1.1 → 6.3.0

293/293 tests pass with bumped constraints.

Co-Authored-By: Claude <noreply@anthropic.com>

* chore(snyk): add [tool.poetry.dependencies] shim with bumped versions

Snyk's GitHub PR app integration uses the legacy poetry parser even when
the org has "uv preview" enabled — preview is CLI-only per their docs:
https://docs.snyk.io/supported-languages/supported-languages-list/python/cli-support-for-uv

Without [tool.poetry.dependencies] in pyproject.toml the snyk PR check
fails with "pyproject.toml error Failed to detect issues" and never falls
through to scan requirements.txt or uv.lock. The shim mirrors the
just-bumped (and verified vuln-free) [project.dependencies] versions so
snyk's legacy parser succeeds without finding any vulns at the constraint
floor.

Pre-commit hook still keeps requirements.txt in sync for redundancy.

Will revert this whole [tool.poetry.dependencies] block once snyk's PR
app integration uses uv preview natively (snyk-python-plugin#251).

Build verified: `python -m build` produces wheel + sdist.
Tests verified: 293/293 pass.

Co-Authored-By: Claude <noreply@anthropic.com>

* fix: address PR #230 review feedback

Triaged comments from coderabbit, gemini-code-assist, codex, and the
ongoing snyk investigation. Three valid actionable items + one false
positive class to flag.

1. Snyk: [tool.poetry] block was incomplete — Poetry requires
   name/version/description/authors as required fields. Without them,
   snyk's poetry parser rejects the block as invalid and reports
   "pyproject.toml error Failed to detect issues" before even getting
   to dependencies. Add the required identity fields, mirroring values
   from [project] above. poetry-core 2.x prefers [project] when both
   are present, so this duplication doesn't affect builds. Verified:
   `python -m build` produces wheel + sdist correctly.

2. coderabbit: attrs missing upper bound for consistency with other
   deps. Added `<27.0.0`. attrs uses year-based major versioning, so
   this caps at the next year boundary — same pattern as other caret
   constraints. Mirrored in [tool.poetry.dependencies] shim.

3. gemini-code-assist (medium) + coderabbit (nitpick): Dockerfile
   builder stage had redundant `apt-get upgrade -y` (already done in
   base stage) and missing `--no-install-recommends`. Removed the
   redundant upgrade and added the flag. Verified: `docker build` +
   `docker run --version` both work.

4. gemini-code-assist (3x "hallucination" comments on attrs 26.1.0,
   ruff 0.15.12, uv 0.11.13): false positives. All three are real,
   current package versions (verified via PyPI / GitHub releases /
   ghcr.io image registry). Gemini's training data appears to predate
   these releases; will reply on the comments rather than change code.

5. codex requirements.txt comment was already addressed in commit
   7aa59b5 by adding `--quiet` to the export command — now generates
   clean output without the resolver status line.

293/293 tests pass. Docker image builds in ~4s. Wheel + sdist build.

Co-Authored-By: Claude <noreply@anthropic.com>

* fix(snyk): remove [tool.poetry.dependencies] shim — it was causing the error

Backwards reasoning: at commit 51ed1f3 (NO [tool.poetry.dependencies])
snyk successfully parsed [project.dependencies] via its uv preview AND
reported the click@8.2.1 vuln. Snyk CAN read PEP 621 deps with preview
enabled; the parser was working.

When I added [tool.poetry.dependencies] alongside in commit 283154b,
snyk started erroring with "Failed to detect issues" — presumably
because two competing dep declarations (PEP 621 vs Poetry-style)
confuse the parser. The shim was the cause, not the fix.

Now that the click bump in commit 28405e6 already cleared the only
real vuln snyk had flagged, the simpler config (just [project], no
shim) should make snyk happy. Keeping a comment explaining why the
shim is deliberately absent so a future contributor doesn't re-add it.

Build verified (wheel + sdist), 293/293 tests pass.

Co-Authored-By: Claude <noreply@anthropic.com>

* fix(security): bump vulnerable deps + add uv install/use compatibility (#105)

Decision after deep evaluation: stay on Poetry as primary, add best-effort
uv support for install/use. Closes #105 not as a full migration but as a
deliberate "support both, canonical = Poetry" position.

Why not full uv migration:
- Snyk's GH App doesn't yet support uv.lock (snyk-python-plugin#251 open).
  Workarounds either break snyk parsing or create dual-lockfile drift risk
  with auto-security-patching bots (dependabot, snyk auto-fix PRs).
- Maintainer has many repos; per-repo migration burden + ecosystem
  friction outweighs the speed gain today.
- uv works fine for install/use from this repo via git+https; full
  migration can land later when the ecosystem catches up.

Changes:

1. Bump dependency lower-bounds to clear known vulnerabilities at the
   constraint floor (snyk scans the lower bound when no specific version
   is locked):
   - click ^8.3.3 fixes SNYK-PYTHON-CLICK-16347201 (HIGH, command injection
     in click.edit() filename param). Was ^8.2.1.
   - aiohttp ^3.13.5 fixes multiple HIGH vulns (SSRF on Windows static
     handler, memory exhaustion in multipart/Request.post/ZLibDecompressor,
     request smuggling). Was ^3.12.0.
   - Other deps bumped to match poetry.lock current resolution: aiodns
     ^3.6.1, attrs >=26.1.0,<27.0.0, maxminddb ^2.8.2, pyyaml ^6.0.3,
     pytest ^8.4.2, pytest-mock ^3.15.1, pytest-cov ^6.3.0.
   - Dropped pytest-runner (deprecated, unused).
   - Added attrs upper bound per coderabbit review.

2. Regenerated poetry.lock with bumped deps.

3. README install warning expanded: do NOT install from PyPI (`proxybroker`
   AND `proxybroker2` names are squatted per #186 and pypi/support#10315).
   Always install from this GitHub repo via git+https.

4. Added uv-as-alternative install instructions alongside the existing pip
   instructions. Both go through git+https, never PyPI. uv invokes the
   build backend (poetry-core 2.x) which synthesizes PEP 621 metadata so
   `uv pip install git+...` and `uv add ... @ git+...` both work.

5. README contributor section: Poetry remains canonical; uv supported as a
   best-effort alternative for local dev (uv.lock NOT committed — avoids
   drift with the authoritative poetry.lock).

6. CLAUDE.md restored to poetry-primary state.

Verified:
- `uvx poetry install` succeeds with bumped deps
- 293/293 tests pass via `poetry run pytest`
- `poetry build` produces wheel + sdist
- `docker build` succeeds, container runs
- `uv pip install <source_checkout>` works (poetry-core builds the wheel,
  uv installs it, `proxybroker --version` returns 2.0.0b3)

Co-Authored-By: Claude <noreply@anthropic.com>

* chore: trigger PR sync to re-run WIP check

* fix: add ruff to dev-deps so documented poetry workflow works (codex #230)

Codex review caught: README's contributor workflow runs
\`poetry run ruff check / format\`, but ruff wasn't in
[tool.poetry.dev-dependencies] — so a clean \`poetry install\`
left contributors with "command not found: ruff" when they tried to
lint/format per the docs.

The CI workflow papered over this by running \`poetry run pip install
ruff\` ad-hoc before invoking it. That kept CI green but broke the
documented contributor flow.

Fix:
- Add \`ruff = "^0.15.12"\` to [tool.poetry.dev-dependencies]. Now
  \`poetry install\` provides ruff, matching README.
- Drop the redundant \`poetry run pip install ruff\` from the CI
  workflow since ruff is now declared properly.
- Regenerate poetry.lock (ruff 0.15.13 picked up; matches the same
  version range as the pre-commit hook in .pre-commit-config.yaml).

Verified: \`poetry run ruff --version\` → 0.15.13. \`poetry run ruff
check . / format --check .\` both clean. 293/293 tests pass.

Co-Authored-By: Claude <noreply@anthropic.com>

* docs(readme): bump stale v2.0.0b1 references to current v2.0.0b3

README had v2.0.0b1 hardcoded in 9 places (install commands, section
headers, callouts) from when that was the latest release. Current
release is v2.0.0b3 per pyproject.toml. When I added uv install
instructions in the parent PR, I blindly mirrored the existing
v2.0.0b1 pattern instead of fixing the staleness — same "consider
3 steps further" miss the maintainer called out earlier.

Fix: replace all v2.0.0b1 → v2.0.0b3.

(Follow-up to keep in mind: every release needs a README sweep to
update these strings. Future improvement: extract to a single
"latest release" reference at top, or use shields.io dynamic badge
that pulls from the latest GitHub release.)

Co-Authored-By: Claude <noreply@anthropic.com>

* docs(readme): make evergreen — drop stale version/count/dep references

Per maintainer review, README should be long-lived with minimal per-release
maintenance. Stale-prone content moves to canonical sources or gets dropped.

Removed (rots on every release/commit):
- "v2.0.0b3" version strings in tagline, section headers, install commands,
  marketing callouts (9 occurrences total)
- "131 tests passing" / "100% test coverage" claims (actual: 293 tests,
  60% coverage minimum). Replaced with qualitative "comprehensive test
  coverage" — verifiable claim that doesn't rot.
- Dep version pins in Requirements section (aiohttp 3.12.0+, aiodns 3.4.0+,
  etc.) — duplicated info from pyproject.toml that goes stale on every bump
- Dev-tool version pins (pytest 8.3.5+, pytest-cov 6.1.1+, ruff X.Y) —
  same reason; pyproject.toml is authoritative
- Embedded `--help` CLI output (~40 lines) — went stale per CLI flag change.
  Replaced with `python -m proxybroker --help` pointer.
- "What's New in v2.0.0b3" section — version-by-version changelog belongs
  in CHANGELOG.md, not README

Restructured (one marketing section, one migration guide):
- New "What's New in ProxyBroker2" merges three previously-overlapping
  sections (the old "What's New in v2.0.0b3", "Why ProxyBroker2?", and
  "What's Improved vs v0.3.2" from Migration). Now describes what
  ProxyBroker2 gives over abandoned v0.3.2 — including IPv6 and custom
  providers that the b3 release actually added.
- "Migration from ProxyBroker v0.3.2" becomes a pure how-to-migrate guide
  (Python version, install command, CLI usage diff, API compat) with a
  cross-link to the marketing section above.

Updated to current security/UX direction:
- Install commands drop @v2.0.0b3 tag — `git+https://...` always pulls
  latest from default branch. Note added pointing to GitHub Releases page
  for users who want to pin: "append @<tag> from Releases".
- "Requirements" section slimmed to "Python 3.10-3.14" — the only thing
  users handle manually; all deps auto-installed.
- "Development Tools" → "What contributors handle manually". Only Poetry +
  optional pre-commit. Dropped ReadTheDocs (project infra, not contributor
  tool) and dropped pinned versions of auto-installed dev tools.
- Migrated TODO list to GitHub issue links (was 7 vague bullets).
- Merged duplicate License sections at lines 636 + 683.
- Removed redundant "TWITTER" badge link area at line 4 in the tagline
  (kept the badges below).

Per-release maintenance now: zero. CHANGELOG.md is the only place that
needs touching per version.

Co-Authored-By: Claude <noreply@anthropic.com>

* Initial plan

* style: apply ruff formatting to test files

* Stabilize IPv4-mapped IPv6 test expectations

* docs: remove unsupported uv sync setup step

* chore(deps): lock aiohttp 3.14.5, multidict 6.9.1, yarl 1.25.1 (advisory fixes)

The FOSSA Security Analysis check on #230 and #238 reports 11 vulnerabilities.
They come from poetry.lock on this branch, not from the resolver change:

- aiohttp 3.14.1: 14 OSV advisories (4 HIGH, published 2026-08-03 and
  2026-10-19/20), all fixed by 3.14.4. Locked to 3.14.5, the latest.
- multidict 6.7.1: GHSA-54p9-h82j-f925 and PYSEC-2026-4244, fixed in 6.9.1.
  Kept on 6.x; 7.0 is a major release (istr can no longer be subclassed).
- yarl 1.24.2 -> 1.25.1, required by aiohttp 3.14.5 (yarl>=1.25.1).

OSV reports no advisories for any of the three locked versions. All three
releases carry PyPI provenance from the aio-libs GitHub repositories.

Only these three packages change. pyproject.toml is unchanged, the
content-hash is unchanged, and the lock was written by Poetry 2.4.1 (same as
the file header).

Verified in a clean python:3.13 container:
- this branch: 293 passed, ruff check clean
- with #238 on top: 294 passed; live resolve of github.com, pypi.org and
  one.one.one.one succeeds through Resolver.resolve()

* fix(resolver): read aiodns 4 DNSResult answers (for #230) (#238)

* fix(resolver): read aiodns 4 DNSResult answers

aiodns 4 query_dns() returns a pycares 5 DNSResult instead of a list of
objects with .host. resolve() iterated the result directly and raised
TypeError: 'DNSResult' object is not iterable on every real lookup.
Read address records from DNSResult.answer[*].data.addr (skipping CNAME
and other non-address records) and keep the legacy query() list shape.

Adds a regression test built from real pycares 5 DNSResult/DNSRecord types.
Found by Lapisa review of PR 230 (aiodns 3 -> 4 at resolver.py:550/552).

* test: isolate DNSResult regression from shared cache

Co-authored-by: bluet <51141+bluet@users.noreply.github.com>

---------

Co-authored-by: Gaia (agent for bluet) <bluet@users.noreply.github.com>
Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: bluet <51141+bluet@users.noreply.github.com>

* docs: make the uv runner command use Poetry's environment; align .gitignore note (review threads on #230)

- README: plain "uv run pytest" after "poetry install" discovers the project, finds no [project] table and runs in
  its own environment, so Poetry's packages are not there. Keep "poetry run pytest" as the canonical command and show
  the uv form that targets Poetry's interpreter: uv run --no-project --python "$(poetry env info --executable)" pytest.
  Verified in a python:3.13-slim container with poetry 2.3.2 and uv 0.13.5: both commands run the suite, 294 passed.
- .gitignore: the uv.lock note no longer suggests "uv sync" (unsupported with Poetry-only metadata, as the README says).

---------

Co-authored-by: Claude <noreply@anthropic.com>
Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: Gaia (agent for bluet) <bluet@users.noreply.github.com>
Co-authored-by: bluet <51141+bluet@users.noreply.github.com>